COMMENT ⊗   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002				       INTRODUCTION
C00006 00003					USING CKSUM
C00016 00004				       FILE CLASSES
C00025 00005				    MISCELLANEOUS NOTES
C00030 00006				RELATIVELY SIMPLE EXAMPLES
C00033 ENDMK
C⊗;
			       INTRODUCTION

CKSUM lets you "keep track" of E-format files, in the sense that when they
change it will tell you which pages the changes are on.  Two typical
applications would be (1) a large source file, where you don't want to sit
through the ATSIGN program just to learn which sections have changed, and
(2) the BBOARD and GRIPES files, where you might not want to scan the E
directory for changes and/or want to find out where some loser added a
comment without doing an NDBBOARD command to update the directory line.

As with most programs, CKSUM has all sorts of obscure features.  This
documentation describes them all, and can thus be somewhat imposing if you
just want to do something simple.  There are some examples at the end
detailing how you would do some of the simpler things.

CKSUM operates by computing a 36-bit checksum (not a straight longitudinal
checksum) for each page of the file, not counting the directory page.  The
file MUST be in E format -- in particular, pages must start on record
boundaries.  (CKSUM will provide a limited amount of information for
unformatted files; see "Files Without Directories" under "Miscellaneous
Notes".)  The checksums, along with the date and time the file was last
written, are kept in the file CKSUM.DAT on your master ([1,xxx]) account.
(If you don't have a [1,xxx] account, you lose.  Create one.)  One
CKSUM.DAT file may contain data for any number of checksummed files.  You
can ask about changes in any or all of the files in one run of CKSUM.
				USING CKSUM

SYNTAX AND SWITCHES
====== === ========

To use CKSUM, the general format is:

.R CKSUM;{files}{switch}

(If both "files" and "switch" are omitted, the semicolon is unnecessary.)
The optional "files" field is a list of file names, separated by commas.
Filehacks (e.g., \M) ARE recognised, but the partial-sign construct is NOT.
Down-arrows may be used to quote odd characters as usual.  If no list of
files is given, then the default is to operate on all the files in
CKSUM.DAT, though you can change this using file classes (see below);
otherwise, only the files named will be used and any not yet in
CKSUM.DAT will be added to it.  (You'll be asked to confirm adding new
files, as a hedge against typoes.)  If CKSUM.DAT does not yet exist, you'll
be asked to confirm initialising, and if you did not give a list of files
you'll be asked again for one; typing a null line to this request gets you
a default of BBOARD and GRIPES.

No more than one switch is allowed.  The available switches are:

/DELETE	      delete (selected) entries from CKSUM.DAT; you'll be asked
	      to confirm this.
/EXIT=<mode>  specify CKSUM's behavior (for you) with regard to swapping to
	      E to look at changes (see below).  /EDIT is recognised as an
	      equivalent switch.  <mode> is one of EXIT, ASK, QUICK, INIT,
	      or NOINIT.
/LIST         just list (selected) files in CKSUM.DAT, together with the
	      date and time of the last checksummed version, and the number
	      of pages in each.
/READONLY     report changes as usual, but don't store the new checksums in
	      CKSUM.DAT (normal operation is to store the new checksums so
	      that you hear of each change only once).
/SORT         show the current list of checksummed files and reorder them
	      in CKSUM.DAT as directed (instructions are provided by the
	      program at that time).
/WRITE        override automatic /READONLY for file classes (see below).

Switches may be abbreviated to single letters.  (Likewise for the <mode>
with the /E switch, as in /E=A.)  If /E or /S is specified, the "files"
parameter MUST be omitted.  If any other switch except /W is present, then
any new files in the "files" parameter are reported and ignored, since /D,
/L, and /R all imply that nothing is to be added to CKSUM.DAT.  Also, a
null "files" parameter is forbidden with the /D switch; if you want to
delete all entries, just delete CKSUM.DAT.  (It's kept delete-protected as
a precaution, but you can of course override that.)


SWAPPING TO THE EDITOR
======== == === ======

After CKSUM has exited, if it reported any new or altered pages (as opposed
to just deleted pages and unchanged files), you can get CKSUM to put you
into E so you can look at those pages.  Exactly how this is done depends on
the "Exit Mode" you've specified.  The default is EXIT and INIT, but you
can override these via the /E switch as noted above.  A setting specified
by the /E switch is applied to all future runs of CKSUM.  The choice among
EXIT, ASK, and QUICK is independent of the choice between INIT and NOINIT,
and you can change only one or the other in a single run of CKSUM.  The
operation of CKSUM in the various modes is as follows:

/E=EXIT:   CKSUM will exit, having written the new CKSUM.DAT file unless
	   everything that changed was in /R mode.  If you then type
	   CONTINUE, CKSUM will swap to E.  If you decide there have been
	   too many changes for you to look at right away, you can type
	   REENTER and CKSUM will restore the CKSUM.DAT file to its
	   previous state, such that you'll hear about the same changes
	   again the next time you look.  (Or you can then run CKSUM again
	   but select a subset of the files to look at.)

/E=ASK:    When CKSUM is done, if there were new/altered pages, it will ask
	   you "Swap to E?".  Type Y to do so (updating CKSUM.DAT along the
	   way), N if you don't want to look at the changes.  If you type
	   N, CKSUM will then ask "Write new CKSUM.DAT?"; type N if you
	   want to throw away the new checksums:  The effect is similar to
	   that of doing a REENTER as described in the preceding paragraph;
	   note, however, that in this mode the new CKSUM.DAT file is not
	   written unless you explicitly ask for it (by answering "yes" to
	   one question or the other).  Thus this provides more of a
	   safeguard against spazzing; in /E=EXIT mode you lose big if,
	   instead of typing CONTINUE, you forget and type some other
	   command such as FINGER or ET.

/E=QUICK:  This is the same as /E=ASK, except that CKSUM won't bother to
	   ask whether you want to swap to E; it'll just do it.  Once
	   you're in E, there's effectively no way to restore the previous
	   CKSUM.DAT file short of using the system UNDELETE command.

/E=INIT:   If you have an "EIN" tmpcor file, which E normally executes
	   automatically whenever you edit anything (e.g., to load in a
	   standard set of E macros), then it will be executed as usual
	   when you swap to E from CKSUM.  (If you don't have such a tmpcor
	   file, don't worry about this.)

/E=NOINIT: Your EIN tmpcor file (if any) will NOT be executed when you swap
	   to E.  That is, it will be as though you specified /-I to E.

When CKSUM puts you into E, it does so with E's file stack containing the
file(s) with new/altered pages and each file having a "mark" placed at the
top of each such page.  (You can also request that the marks be at the ends
of pages; see the section on File Classes.)  Thus you can then use αM
commands to look at pages until you come back to one you've already seen,
then use α+αH to get to the next file, etc.  Note that this destroys the
tmpcor file used by E to remember the last few files you edited prior to
running CKSUM.

The REENTER feature described above works any time the CKSUM.DAT file has
been changed, provided you do nothing else (not even rerun CKSUM) first.
For instance, if you make some changes to the file class assignments (see
section on File Classes), and then decide you blew it, you can type REENTER
right away to undo your changes.
			       FILE CLASSES

CKSUM lets you specify up to 27 "classes" of files, identified by the
letters A through Z and the digit 0.  By default, all files start out in
class 0.  Each file class has a set of flags associated with it, selecting
various options affecting files in that class.  Each option corresponds to
a bit in a 9-bit field (sort of like file protections), as follows:

bit	  option			   description
---	-----------	---------------------------------------------------
001	implicit /R	Files in this class are automatically treated as
			/READONLY; that is, changes to the files will be
			reported but the new checksums will not be saved.
			This lets you keep track of the cumulative changes
			to some files while looking at day-to-day changes
			in others.  You can force CKSUM to save the new
			checksums for these files via the /WRITE switch.
002	exclusion	Files in this class are NOT processed if you run
			CKSUM without giving an explicit list of files
			(either by name or by file class).
004	mark bottom	If you swap to E, the marks in these files will be
			at the bottoms of the pages instead of the tops.
010	change only	Files in this class will not be mentioned at all
			unless they have been written since the last time
			they were checksummed.
020	no E dir	CKSUM will not warn you if these files lack a valid
			E directory.  If you swap to E, /R (E's /R, not CKSUM's)
			will NOT be specified for these files (normally, a file
			lacking a directory will be edited in /R mode).
040	invis changes	If a file in this class is changed (as indicated by its
			date-last-written), then even if there are no new or
			altered pages, the file will be included in the list if
			CKSUM swaps to E.
100	edit /R		If you swap to E, files in this class will always be
			edited in /R mode, even if they have an E directory.
			This is particularly useful when using checksum to keep
			track of changes in someone else's files (so you want to
			be particularly careful not to alter them accidentally)
			or in conjunction with the 020 and 040 mode bits (to
			let you know when an unformatted multi-page file has
			been changed, even though CKSUM can't pinpoint the new
			pages due to the file's being unformatted).
600	   --		The remaining option bits are currently unused.

The initial defaults are 0 for class 0 and 1 (readonly) for classes A-Z.


PUTTING FILES INTO CLASSES
======= ===== ==== =======

To change the class a file is in, include in the "files" parameter the file
name followed by =X where X is the class to put it in.  Thus, for example,
B CKSUM;\BBOARD=X,\GRIPES=Y puts the BBOARD file in class X and the GRIPES
file in class Y.  When you specify a class for a file, that file will not
be checksummed during that particular run of CKSUM unless you explicitly
list the file a second time, as in R CKSUM;FOO=X,FOO.  (Similarly, if in
addition to changing some files' classes, you include files in the list
without any "=" specification, those files will be checksummed as usual.
Files that are being added to the CKSUM.DAT records for the first time are
always checksummed in order to establish their current state.)


USING FILE CLASSES IN THE "FILES" LIST
===== ==== ======= == === ======= ====

You can also use classes in place of file names.  A list of one or more
file classes enclosed in parentheses is equivalent to listing all the files
in those classes.  Thus, after the above class-setting example, the command
R CKSUM;(XY) would show changes to BBOARD and GRIPES (but would not save
the new checksums, since classes X and Y default to /R).  R CKSUM;(X)/W
would show changes to BBOARD and WOULD save the new checksums for it, and
R CKSUM;(Y)=0,(X)/W would show (and remember) changes to BBOARD and put
GRIPES into class 0.  The special specification (∀) requests ALL classes.


SPECIFYING OPTION BITS
========== ====== ====

To change the option bits associated with a file class, give the file class
(or classes) in parentheses and follow the close parenthesis with a colon
and then the octal value obtained by ORing the desired bits.  For example,
R CKSUM;(0B):4,(XY):5 would specify that classes 0, B, X, and Y all get
marks placed at the bottoms of pages instead of the top, and that X and Y
are readonly (unless overridden by /WRITE) while 0 and B are not (unless
explicitly requested by /READONLY).  A typical setting is "(∀):3,(0):14",
such that you check only on files in class 0 unless you explicitly ask for
the others (probably via something like R CKSUM;(X) ), and for the
frequently-checked files (class 0) you're not told about lack of changes.
It also makes files outside class 0 default to /R and files in class 0
have marks put at the bottoms of pages.


FILE CLASSES IN /LIST OUTPUT
==== ======= == ===== ======

The /L output includes the file class in parentheses for all files listed
that are not in class 0, and also lists the option settings for classes
included in the command line (all classes if the "files" parameter was
omitted) that have non-default settings.
			    MISCELLANEOUS NOTES

RENAMING FILES
======== =====

If a file you have been checksumming gets renamed, CKSUM will complain that
it can no longer find the file.  You could just delete the file from your
list and add the new name, but that would mean recomputing all the checksum
information for that file and thus missing out on hearing about changes
that occurred around the time of the rename.  To handle this situation, you
can tell CKSUM that the file has moved by including <newname>←<oldname>
somewhere in the "files" list.  Just as when you change a file's class, the
rename entry in the list does not cause the file to get checksummed this
time around unless you explicitly list the (new) name a second time.  You
can combine renaming with class-changing, as in FOO←BAR=X.


DETECTING CHANGES
========= =======

CKSUM does not bother recomputing checksums unless the file in question has
been changed (based on date/time last written), so it should be moderately
fast when there's nothing to report.  If the only change has been an
invisible one like updating the E directory (via E's αXUPDATE command)
without changing any other pages, or "burping" one or more pages, CKSUM
will report that the file has been edited with no visible effect.

When reporting changes, CKSUM does its best to figure out what has actually
happened to the file.  If pages have moved around without being changed, it
reports where they have moved to.  If pages have been deleted or added with
no other changes occurring, it reports that.  But if deletions or additions
occur together with other changes, CKSUM has no way of knowing which pages
were deleted/added and which changed; in this case it reports the change in
the total number of pages and says which pages in the new file fail to
match any in the old one.


FILES WITHOUT DIRECTORIES
===== ======= ===========

If you ask to checksum a file that lacks a valid E directory, CKSUM will
complain (unless the file belongs to a class with the "no E dir" option),
but it will still compute the checksums for any pages (other than page 1)
that happen to start on record boundaries.  Thus, in particular, if you
checksum a one-page file, you will be informed thereafter whenever the file
is edited, even though CKSUM will be unable to find any differences.  By
using the "no E dir" and "invis changes" options, you can get CKSUM to
include the file in the list when you swap to E.  This can prove useful
for such files as \DIGEST.


OTHER WAYS TO RUN CKSUM
===== ==== == === =====

If you have a CKSUM.DAT file, then the CKMAIL command (abbreviated CK) will
swap to CKSUM after reporting whether you have mail or news notifications,
unless you tell it you want to check somebody's mail other than your own.
Since CKMAIL ignores everything out to the first space, you can even say
things like CK/R or CK(X)/W and get away with it.

If you include RUN=CKSUM in your LOGIN options in OPTION.TXT, then LOGIN
will swap to CKSUM when it finishes logging you in.  CKSUM will act as
though you invoked it with no "files" parameter and no switch specified.
			RELATIVELY SIMPLE EXAMPLES

The preceding documentation is somewhat exhaustive; if all you want to do
is some relatively simple stuff, these examples may help.  First, if all
you want to do is keep track of BBOARD and GRIPES:

.R CKSUM;\B,\G		(the first time)
.R CKSUM		(thereafter)

You might want to have the marks placed at the ends of pages in those
files, since that's where new stuff shows up.  In that case, either

.R CKSUM;\B,\G,(0):4	(the first time)

or

.R CKSUM;(0):4		(if you think of it after already running CKSUM
			for the first time)

If you want to keep an eye on the BBOARD and GRIPES files from day to day,
and also have a source file MUMBLE.SAI in which you want to be able to
identify changed pages for spooling after an edit (and thus you don't want
to check it every day -- just after an edit):

.R CKSUM;\B,\G,(0):4,MUMBLE.SAI=X,(X):3

What this does is put BBOARD and GRIPES into class 0 with marks at ends of
pages, as before, and also puts MUMBLE.SAI into class X with the exclusion
and readonly bits selected.  Since MUMBLE.SAI is being added to the list,
it will be included in this initial run (overriding the newly-set exclusion
bit) so that the initial checksums will be computed.  On later runs:

.R CKSUM		(tells you about changes in BBOARD and GRIPES)
.R CKSUM;(X)		(tells you about changes in MUMBLE.SAI so you can
			spool the altered pages)
.R CKSUM;(X)/W		(same as without /W but also updates the checksums
			for MUMBLE.SAI in the CKSUM.DAT file, so you won't
			get told about those changes again)

.R CKSUM;CRITIC.TXT[2,2/D
			deletes CRITIC.TXT[2,2] from your list of files
Comments, suggestions, bugs, etc., via GRIPE CKSUM.